home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 4 / CU Amiga Magazine's Super CD-ROM 04 (1996)(EMAP Images)(GB)(Track 1 of 3)[!][issue 1996-11].iso / magazine / psion / utils / jbst13.lzx / jbsort.txt < prev   
Text File  |  1995-02-14  |  13KB  |  429 lines
  1.                                 JBSort
  2.                              Version 1.3
  3.                            (c)JBSoft 1994/5
  4.  
  5.                                   ³
  6.                                   ÃÄ¿
  7.                                 ÀÂÁÄÙ
  8.                                  ÀÄ¿
  9.                                  ÄÄÙ
  10.  
  11. JBSort is a utility to sort Data files by ASCII. It will, in fact,
  12. sort any database files created with Data or by the Psion OPL CREATE
  13. command. It works on both the S3 and S3a.
  14.  
  15. The program is normally started from the System screen by choosing a
  16. file listed under the JBSort icon. Alternatively, whilst the cursor is
  17. in the filelist below the JBSort icon, press Tab - this will enable
  18. you to navigate through the directories and drives in the normal way.
  19. Once the file to be sorted has been found and highlighted with the
  20. cursor, press Enter.
  21.  
  22. There is now extensive checking for memory availability and, should
  23. the program fail for lack of memory at any time, the system should be
  24. cleared of any temporary files made by the application at the time of
  25. the failure.
  26.  
  27. Alternatively, the application can be started from another program
  28. using the Operating System call that has been documented in many
  29. places (see Appendix A for details of the call) - if you provide a
  30. datafile name with this call then the application will automatically
  31. select that program for sorting. If no filename is given then a dialog
  32. is displayed enabling you to chose the file to sort.
  33.  
  34. The program can be run in the background but there may be a slight
  35. blip on the screen when the program is started - this is unavoidable
  36. without a total rewrite in Object Oriented Code. If it is run in the
  37. background then sensible defaults are used so that user inputted data
  38. is unnecessary. The program, when run in the background, will sort in
  39. ascending order using the first three fields as the key fields in the
  40. order in which they appear - it will over-write the existing file.
  41.  
  42. If the datafile chosen is open, an option is given to continue the
  43. sort or not. If it is decided to continue, and the file hasn't been
  44. opened by a program with the data details hard-coded, then the file
  45. will be closed and, after the sort, will be re-opened.
  46.  
  47. There is a small problem with the S3 in that, when the file is re-
  48. opened, the front screen will show the Application name (e.g. Data)
  49. rather than the filename. This can be cured by pressing the System
  50. button or going into the file. This problem is being investigated but
  51. I have no idea why it is happening so I don't hold out much hope for a
  52. proper fix.
  53.  
  54. N.B. As far as I can tell, it is impossible to find the owner of a
  55.      datafile opened in an application that doesn't have a filelist,
  56.      therefore the sort application will fail if a datafile currently
  57.      open by such an application is selected. This state is only true
  58.      of programs which don't have filelists - programs with lists will
  59.      work!
  60.  
  61. If run normally, a dialog is presented so that the Fields on which to
  62. sort can be chosen. If you only wish to sort on the one field then
  63. make all three field choices the same or, if you wish to sort on two
  64. fields, make fields two and three the same. The last option in the
  65. fieldnames list is <none> which can be selected as an alternative to
  66. making the choice the same as the previous selection.
  67. Next, if run on an S3, another dialog is shown to enable you to
  68. specify a new filename in which the resultant sort will be placed,
  69. otherwise, on an S3a, this data choice is included in the field choice
  70. dialog. You may also specify a forwards or backwards sort (e.g. ABC or
  71. CBA) and also, once the sort is completed, whether to exit the program
  72. or choose another file to sort.
  73.  
  74. Once this initialisation has been carried out the program will then
  75. sort the file and either exit or end on a file selection dialog where
  76. you can choose another file to sort.
  77.  
  78. The program works by creating a string (made up of the three field
  79. choices in order) for each record along with the position of the
  80. record in the file. This string is then sorted and the result is then
  81. written in the appropriate order to another file. Assuming that
  82. another file has not been specified for the result, the original file
  83. is then deleted and the new file renamed to that of the original.
  84.  
  85. To enable large data files to be sorted I have included a fall-back
  86. procedure that is hierarchical and works in the following order:-
  87.  
  88.      1. As specified.
  89.      2. Limit length of each field to 8 characters.
  90.      3. Reduce by one the number of fields to be sorted.
  91.      4. Repeat 3 until only one field is left - if it still fails then
  92.         the program fails.
  93.  
  94. Obviously, the further down the tree the program has to go, the longer
  95. it will take to complete its task.
  96.  
  97. Should the program fail at some point in the procedure then there
  98. should be no lasting damage as the last thing the program does is
  99. delete the original and substitute the new file, prior to that, the
  100. original file is not altered in any way. If the option to over-write
  101. was chosen and the program fails, there may be a file called JBZZ.DBF
  102. created. This can be deleted with no problems (this is the file that
  103. is renamed as the last action of the program).
  104.  
  105. Limitations
  106. -----------
  107. The main limitation to my program is the 64k limit on data in any
  108. program (this 64k limit does not refer to the database size but the
  109. amount of data that an application can have). The actual sort takes
  110. place in memory and so there is a great deal of data temporarily held
  111. there. The probable limit to the size of the database is going to be
  112. around 5,000 entries but this is purely theoretical and could be
  113. wildly out. If you come across a database whose sort fails through
  114. lack of memory I would be grateful of that information along with the
  115. number of records (and type of fields being sorted) so that I can
  116. update this section of the 'manual'.
  117.  
  118. Sort is limited to 3 fields at present (again, this could be increased
  119. given the necessity).
  120.  
  121. The program requires sufficient space on the drive to create a
  122. duplicate file of the same length as the first file. The program
  123. checks for this availability and, if there is insufficient memory
  124. available, the program will fail. The program will also fail if there
  125. is insufficient RAM in which to run. As a guide, the program itself
  126. requires around 60k but this is variable and is somewhat related to
  127. the size of the file being sorted - it is impossible to give accurate
  128. figures due to variability of the files being sorted.
  129.  
  130. Bearing in mind I am a one-man-band and do not have access to every
  131. application going, it is possible that there is an program out there
  132. that creates data files which will not sort correctly, although I have
  133. not come across any so far. Should you encounter one of these, please
  134. let me know, and, if possible, provide a sample file so that I can
  135. adjust (fix) my program accordingly.
  136.  
  137. Thanks
  138. ------
  139. As usual, thanks go to Tom Dolbilin for his assistance in shaping this
  140. program. I would also like to thank Paul Steel for checking some
  141. things out and pointing out some problems.
  142.  
  143. Contact
  144. -------
  145. John Boyce
  146. CompuServe: 100014,1240
  147. CIX/Internet: jboyce@cix.compulink.co.uk
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199. Appendix A
  200. ==========
  201. The OS Call mentioned above is detailed in this Appendix.
  202.  
  203. Some explanation of the code will be necessary - here it is...
  204.  
  205. appname$ is the name of the application to run. It should include the
  206. path (e.g. "LOC::A:\APP\JBSORT.APP"). This is just a normal string.
  207.  
  208. cmdline$ is a complex string which presents a command line to the OS.
  209. It is made up of several parts:-
  210.  
  211.      1. Command byte &        This can be one of three characters:-
  212.                               O - open an existing file
  213.                               C - create a new file
  214.                               D - open an existing file in the
  215.                                   background (this only works for some
  216.                                   utilities - definitely not OPO or
  217.                                   OPA programs)
  218.                               These characters should be appended to
  219.                               the start of the Header string.
  220.         Header string         This is the public name under which the
  221.                               App appears (e.g. Data or Word or
  222.                               JBSort)
  223.      2. Default extension     This is the default extension for the
  224.                               file to be opened (e.g. .DBF)
  225.         & alias info          This is for alias information and should
  226.                               be separated from the extension data by
  227.                               a space
  228.      3. Data file to open     this should include the path of the file
  229.                               as well as the name
  230.  
  231. Each of the sections should be followed by a zero character - e.g.
  232.  
  233. "OJBSort"+chr$(0)+".DBF"+chr$(0)+"LOC::A:\DAT\ADDRESS.DBF"+chr$(0)
  234.  
  235. ppid% should be the address of an integer in which will be placed the
  236. process identity once the program has been started. This information
  237. can be discarded once the program has been run if no other actions are
  238. to be made on the running application (process).
  239.  
  240. Using the above examples as a guide, runapp% would be called thus:
  241.  
  242. err%=runapp%:("LOC::A:\APP\JBSORT.APP","OJBSort"+chr$(0)+".DBF"+chr$(0
  243. )+"LOC::A:\DAT\ADDRESS.DBF"+chr$(0),addr(pid%))
  244.  
  245. where the code should all be on one line of your program.
  246.  
  247. Almost any program can be run in this fashion, but to run OPO and OPA
  248. programs they have to be treated as files and the application name to
  249. be specified as the appname$ is ROM::SYS$PRGO.IMG. If an OPA file
  250. requires a file then this should be placed in the position of the OPA
  251. name and an extra parameter added which should be the application
  252. e.g.:
  253.  
  254. err%=runapp%:("ROM::SYS$PRGO.IMG","ONotepad"+chr$(0)+".PAD"+chr$(0)+"L
  255. OC::A:\NOTE\NOTEPAD.PAD"+chr$(0)+"LOC::A:\APP\NOTEPAD.OPA"+chr$(0),add
  256. r(pid%))
  257.  
  258. is an example of running Mark Esposito's Notepad program).
  259.  
  260. I have tried to include a lot of information on this call as there is
  261. nothing worse than getting just a little of the information and having
  262. to ask around for the rest. Obviously, the last few items discussed
  263. are not relevant to the current situation.
  264.  
  265. The aliases discussed earlier are a little too complex to explain in
  266. the context of this document and are dependant on the application
  267. recognising them (they also differ for each application so a list is
  268. not relevant).
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331. Code
  332. ----
  333.  
  334. PROC runapp%:(appname$,cmdline$,ppid%)
  335.      local ax%,bx%,cx%,dx%,si%,di%
  336.      local ret%,flags%
  337.      local cmdl$(128),img$(128)
  338.      cmdl$=cmdline$
  339.      img$=appname$+chr$(0)
  340.      ax%=$0100
  341.      bx%=addr(img$)+1
  342.      cx%=addr(cmdl$)
  343.      di%=ppid%
  344.      flags%=os($87,addr(ax%)) REM FilExecute
  345.      if (flags% and 1)
  346.           ret%=(ax% and $FF)-256 REM If a problem set ret% to err
  347.      else
  348.           ax%=$0600
  349.           bx%=peekw(ppid%)
  350.           flags%=os($88,addr(ax%)) REM ProcResume
  351.           if (flags% and 1)
  352.                ret%=(ax% and $FF)-256 REM set ret% to err
  353.           else
  354.                ret%=0
  355.           endif
  356.      endif
  357.      return ret% REM return problem (zero if none)
  358. ENDP
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397. Release Information
  398. ===================
  399. Version   Information
  400. ---------------------
  401. 1.0       First release to the public domain.
  402.  
  403. 1.0a      Bug-fix to actually make the program work on an S3!
  404.  
  405. 1.1       Dialogs are now shown differently if run on an S3 or an S3a
  406.           and appear in the style appropriate to the machine.
  407.           If the datafile is open, it can be closed and re-opened
  408.           under some circumstances.
  409.           Fixed occasional problem with making OPL Datafiles into Data
  410.           type files.
  411.           Added option to stay within the program after the sort is
  412.           complete.
  413. 1.1.1     Stopped machine from switching off when sorting large
  414.           databases.
  415.           Increased memory availability checking to stop occasional
  416.           corruption of sorted file.
  417. 1.1.2     Now closes database gracefully (allowing any changes to be
  418.           saved).
  419.           Cured problem of Alert when answering No to Close Datafile
  420.           dialog.
  421. 1.1.2a    Will now search larger files before running out of memory.
  422.           Fixed obscure bug with release of memory.
  423. 1.2       Fixed problem with sorting single character fields.
  424.           Now dynamically sizes memory so no absolute limit to file
  425.           size.
  426. 1.3       Warnings of memory and Flash sorting are now accurate.
  427.           Created grow line for reading and writing data.
  428.           Fixed problem of re-opening files sometimes failing.
  429.